PD Collection CD 1/PD Collection CD 1.iso/programer2/euclidlib/h/ewindow

Text File | 1992-05-02 | 11KB | 232 lines

/**** ewindow.h ****/
/* Handles windows with euclid pictures in them
 * By Paul Field
 * See !ReadMe file for distribution/modification restrictions
 *
 * N.B. To define the position/size/work area etc of each ewindow, use
 * 'template_syshandle("ewindow")' to get at the window's template and alter
 * it to suit you before you call 'ewindow_create'.
 * Notice that the euclid picture is drawn with its origin at (0,0) so you will
 * probably need negative work area coordinates.
 * I may alter 'ewindow_create' or add some new functions to allow you to define
 * features of ewindows.
 *
 * Things you should be careful of :
 * 1) This module catches palette and mode changes using an 'unknown event processor'
 *    (see win.h). If you use unknown event processors yourself make sure they do not
 *    block palette and mode change messages.
 * 2) Palette changes cause sprites to be redrawn unless they are in raytracing style.
 *    This is likely to change. I will probably add a function that allows you to
 *    choose whether pictures are redrawn on palette changes.
 * 3) This module uses 'alarm.h' to handle multitasking drawing. Under various
 *    circumstances it will remove all alarms with a particular ewindow as a handle.
 *    (I can probably get round this if it is a problem to anyone).
 * 4) This module will also remove processes from a cache's pending queue if they
 *    have a particular ewindow as a handle. (Again, I can probably get round this).
 * 5) Don't change the drawing cache of a structure once it is registered with a window.
 *    (If anyone needs to do this - let me know)
 * 6) If you are using multitasking windows then a structure's drawing cache may
 *    be in use at any time. If you need to use the cache for something
 *    (e.g. drawing into a sprite) then use 'cache_callwhenfree()' to call
 *    your routine. If none of your windows are multitasking or every picture has its
 *    own drawing cache then you do not need to do this.
 * 7) Euclid draws the graphs in inverse in 2 and 4 colour modes on the desktop.
 *    I have arranged the display of sprites so that they do this too.
 *    This means that 256-colour sprites are plotted using colourtrans while
 *    2,4 and 16-colour sprites are plotted useing the desktop colours.
 *    I don't know if this matters to anyone - but I'd thought I'd mention it.
 *
 * Also note :
 * 1) The module should use flex and it is written so that registering 'flex_budge'
 *     with _kernel_register_slotextend() should work.
 *     Unfortunately, Euclid doesn't like it if the flex block
 *     moves between it drawing sections of a multitasking picture.
 *     Tony Cheal (Euclid's author) has told me that it is impractical to move the
 *     cache around during drawing so, for the moment, I have used 'heap_alloc' and
 *     you shouldn't use 'flex_budge'.
 *     I have an idea that may allow the cache and picture (and maybe a sprite
 *     being drawn to) to all be in flex blocks. It may be implemented in a later
 *     version of the module. (If you particularly need the feature contect me
 *     and badger me to put it in).
 *
 * If you use the sprite mode in any windows then you should make its use
 * user-configurable - the user has a fair idea how much memory is needed for other
 * things and so should decide whether to have this memory-hungry feature or not.
 *
 * Using sprites in windows can take up a lot of memory, so I may try using some sort of
 * compression. Decompressing a sprite should still be much faster than asking euclid
 * to redraw the picture.
 *
 * IMPORTANT :
 *   I really need feedback about this module, especially comments on the sprite
 * and multitasking features. I need to know whether function calls for setting up
 * windows are easy or cumbersome to use and if you'd prefer a different way
 * of doing things. For example, instead of including 'closefn' as a parameter
 * in ewindow_create I could add a function 'ewindow_registerclosefn(...)' or
 * perhaps a function 'ewindow_registereventhandler(...)' which passes all window
 * events onto your function.
 * I could also add event handlers for events such as:
 *   update finished
 *   draw called  (could be used to access 'infoblock' or
 *                 to draw in 'extras' over the picture)
 * I also need to know what aspects of windows you need to change
 * (e.g. workarea, picture displayed within, cache).
 * To make this module work I need to know what you are trying to do with it
 * and what problems it gives you.
 */

#ifndef __ewindow_h
#define __ewindow_h

#include "euclid.h"
#include "wimp.h"

typedef struct ewindow_str *ewindow;  /* An opaque type */


typedef void (*ewindow_closefn) (ewindow, void *);

ewindow ewindow_create(const char *title, euclid_drawstyle, euclid_header *structure,
                       const char *camera, ewindow_closefn, void *handle);
 /* Creates a window from the Template 'ewindow' which displays the picture
  * refered to by 'structure' in the style given as seen from 'camera'.
  * (camera may be NULL).
  * If the user clicks on the window's 'close' icon 'ewindow_closefn' will be called
  * (with 'handle' as its second argument) so that you can :
  *   i) Query that the user really wants to close the window
  *  ii) Tidy up any data structures you might have
  * iii) Either close or destroy the window
  *
  * Returns a window structure or NULL if there was not enough memory.
  * You may have multiple windows open.
  * (Window mode defaults to no sprite and no timeout).
  * You should have called 'template_init' and 'flex_init' before you call this.
  * (And for the moment 'heap_init' must be called too - this should not be necessary
  *  in later versions)
  */

typedef enum ewindow_spritemode
 { ewindow_smcurrent = -2, ewindow_smdynamic
 }
ewindow_spritemode;

void ewindow_usesprite(ewindow ew, BOOL sprite, ewindow_spritemode);
 /* If 'sprite' is TRUE the window will attempt to draw the euclid picture in a sprite
  * and then use this during window redraws (which speeds them up considerably).
  * If there is not enough memory to create a sprite then the window will
  * use euclid to redraw the screen until the memory is available. (It detects
  * this on mode and palette changes).
  * 'ewindow_create' defaults to not using sprites.
  * The sprite mode parameter specifies the mode of the sprite. There are two
  * special values :
  *   ewindow_smcurrent - use the current screen mode as the sprite mode
  *   ewindow_smdynamic - use the current screen mode as the sprite mode and whenever
  *                       the screenmode changes recreate and redraw the sprite in the
  *                       new mode. (Also redraws on palette changes).
  */

void ewindow_timing(ewindow ew, char timeout, unsigned int drawgap);
 /* Drawing euclid pictures usually hogs the processor. This call allows picture
  * drawing to occur in several steps (vital if you are going to use the raytracing
  * style). 'timeout' is the number of centiseconds that euclid will spend drawing
  * the picture at one time (roughly).
  *  timeout == 0     - no timeout
  *  timeout == 0xff  - infinite timeout (keep going until mouse event)
  * 'drawgap' is the number of centiseconds between 'spurts' of drawing.
  * 'ewindow_create' defaults to no timeout.
  *
  * Currently multitasking only occurs if a sprite is being used in the window.
  * It is possible (although difficult) to perform a multitasking draw without
  * using sprites and I might try to do this in a later version if I think it is
  * worth the effort.
  */

void ewindow_closeoptions(ewindow ew, BOOL freesprite);
 /* If the 'freesprite' is 'TRUE' then whenever the window is closed any sprite
  * memory associated with it will be freed, if it is 'FALSE' the sprite remains
  * intact and any processes (i.e. drawing) continue to work on it.
  *
  * The option set using this call only has an effect when the 'ewindow_close'
  * is called.
  * This call is mainly useful if you are ray-tracing since you may wish to close
  * the window onto the ray-traced picture without losing the picture.
  * 'ewindow_create' defaults to 'freesprite = TRUE'.
  */

BOOL ewindow_hassprite(ewindow ew);
 /* Returns TRUE if the window has a sprite associated with it.
  */

BOOL ewindow_sprite(ewindow ew, sprite_area ***area, int *offset);
 /* Returns TRUE if the window has a sprite associated with it and returns
  * details of the sprite in 'area' and 'offset'.
  * (Be careful the sprite may not be completely drawn - use 'ewindow_spritecomplete'
  *  to check this)
  * Don't be scared by the triple-indirection, this is necessary because the sprite
  * area is a flex block. You should use the call like this :
  *    { sprite_area **area;
  *      int offset;
  *
  *      if (ewindow_sprite(ew, &area, &offset))
  *       { sprite_id id;
  *
  *         id.tag = sprite_id_addr;
  *         id.s.addr = (char *)(*area) + offset;
  *          || Now you have a direct reference (id.s.addr) don't do anything that
  *          || might move the flex block (see Acorn ANSI C Release 4 manual pp363-4)
  *         sprite_xxxx(*area, &id, ....);
  *       }
  *    }
  * Do not alter the thing that 'area' points to, i.e. don't do anything like
  * '*area = NULL' or attempt to free it, unless you would like your program
  * not to work.
  */

BOOL ewindow_updatecomplete(ewindow ew);
 /* Window using sprite :
  *   Returns TRUE if the sprite is completely drawn.
  *   (i.e. will return FALSE if the sprite is not drawn or is part way through
  *   being drawn (multitasking pictures only)).
  * No sprite :
  *   Returns TRUE if the window has no updates pending
  */

void ewindow_setstyle(ewindow ew, euclid_drawstyle);
 /* Changes the drawing style of the window. If the style is different from before
  * then the window will be updated.
  */

void ewindow_open(ewindow);
 /* Opens the window (at the top of the window stack).
  */

void ewindow_update(ewindow);
 /* If the picture changes, call this to redraw the picture.
  * If the window is sharing a drawing cache with multitasking pictures then
  * the update may not occur immediately - you can use 'ewindow_updatecomplete'
  * to check that it has occured.
  * (N.B. Wimp redraws are handled automatically).
  */

void ewindow_close(ewindow);
 /* Closes the window.
  * Sprite memory is released if the window is using it.
  */

void ewindow_destroy(ewindow);
 /* Closes the window and destroys the window structure
  */

wimp_w ewindow_handle(ewindow);
 /* Returns the wimp window handle so that you can do low-level things (such as
  * attaching menus).
  * Be careful what you do with the window, some things may caused undefined behaviour.
  * Especially, don't alter the work area, and use the functions given for things like
  * opening, closing or deleting the window.
  *
  * I am likely to add routines to this module that allow manipulation of the window
  * i.e. changing its work area, position and size. If you want anything in particular
  * included then contact me (contact points are in the !ReadMe file).
  */
#endif